<html><head><title>Input sequence module reference</title>
<link rel=stylesheet Type=text/css href='../../../../doc/bmxstyle.css'>
</head><body>
<table width=100% cellspacing=0><tr align=center><td class=small>&nbsp;</td>
<td class=small width=1%><b>jmd.inputsequence:</b></td>
<td class=small width=1%><a href=#consts class=small>Constants</a></td>
<td class=small width=1%><a href=#functions class=small>Functions</a></td>
<td class=small width=1%><a href=#types class=small>Types</a></td>
<td class=small width=1%><a href=#modinfo class=small>Modinfo</a></td>
<td class=small width=1%><a href='../../../../mod/jmd.mod/inputsequence.mod/inputsequence.bmx' class=small>Source</a></td>
<td class=small>&nbsp;</td></tr></table>
<h1>Input sequence module</h1>
This module provides a simple yet powerful input sequence acceptance interface.
With this module, it is easy to add cheat codes and easter-eggs to your own game! This module
can also be used where you need to perform actions on certain input sequences, such as
"power moves" in fighting games.
<p>
Each input sequence is thought to be made up of any number of "strokes". A stroke is simply an
input from the keyboard, mouse or joystick. A single stroke can consist of multiple simultaneous key/button
presses - this kind of stroke is referred to as a "macro-stroke".
<h2><a name=consts></a>Constants Summary</h2><table class=doc width=100%><tr><td colspan=2>
<a href=#JOY_STROKE>JOY_STROKE</a>
, 
<a href=#KEY_STROKE>KEY_STROKE</a>
, 
<a href=#MOUSE_STROKE>MOUSE_STROKE</a>
</td></tr>
</table>
<h2><a name=functions></a>Functions Summary</h2><table class=doc width=100%>
<tr><td class=docleft width=1%><a href=#CreateInputSequence>CreateInputSequence</a></td><td class=docright>
Create a new Input Sequence.
</td></tr>
<tr><td class=docleft width=1%><a href=#FreeInputSequence>FreeInputSequence</a></td><td class=docright>
Release the TInputSequence instance.
</td></tr>
<tr><td class=docleft width=1%><a href=#InSeqAddKeyStrokesFromString>InSeqAddKeyStrokesFromString</a></td><td class=docright>
Batch add keystrokes from a string.
</td></tr>
<tr><td class=docleft width=1%><a href=#InSeqAddStroke>InSeqAddStroke</a></td><td class=docright>
Add to the Input Sequence.
</td></tr>
<tr><td class=docleft width=1%><a href=#InSeqClear>InSeqClear</a></td><td class=docright>
Clear all strokes from Input Sequence.
</td></tr>
<tr><td class=docleft width=1%><a href=#InSeqEntered>InSeqEntered</a></td><td class=docright>
Track Input Sequence successes.
</td></tr>
<tr><td class=docleft width=1%><a href=#InSeqResetEntered>InSeqResetEntered</a></td><td class=docright>
Reset the Input Sequence tracking.
</td></tr>
<tr><td class=docleft width=1%><a href=#InSeqSuccessful>InSeqSuccessful</a></td><td class=docright>
Check If an Input Sequence was successfully entered.
</td></tr>
<tr><td class=docleft width=1%><a href=#InSeqUpdateAll>InSeqUpdateAll</a></td><td class=docright>
Update all InputSequences.
</td></tr>
</table>
<h2><a name=types></a>Types Summary</h2><table class=doc width=100%>
<tr><td class=docleft width=1%><a href=#TInputSequence>TInputSequence</a></td><td class=docright>
TInputSequence type.
</td></tr>
<tr><td class=docleft width=1%><a href=#Tstroke>Tstroke</a></td><td class=docright>
TStroke type.
</td></tr>
</table>
<h2
 id=constsdet>Constants
</h2>
<table class=doc width=100% cellspacing=3 id=JOY_STROKE>
<tr><td class=doctop colspan=2>Const JOY_STROKE:Int</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright><b>strokeType</b> constant.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>Used as a parameter to the <a href=#InSeqAddStroke>InSeqAddStroke</a>() function.</td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=KEY_STROKE>
<tr><td class=doctop colspan=2>Const KEY_STROKE:Int</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright><b>strokeType</b> constant.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>Used as a parameter to the <a href=#InSeqAddStroke>InSeqAddStroke</a>() function.</td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=MOUSE_STROKE>
<tr><td class=doctop colspan=2>Const MOUSE_STROKE:Int</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright><b>strokeType</b> constant.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>Used as a parameter to the <a href=#InSeqAddStroke>InSeqAddStroke</a>() function.</td></tr>
</table>
<br>
<h2
 id=functionsdet>Functions
</h2>
<table class=doc width=100% cellspacing=3 id=CreateInputSequence>
<tr><td class=doctop colspan=2>Function CreateInputSequence:TInputSequence(timeOut:Int=500)</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>Create a new Input Sequence.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>Create a new nput Sequence. The <b>timeOut</b> parameter specifies the amount of time
in milliseconds that is allowed between each stroke of the Input Sequence. Smaller values
will require the user to have to enter the Input Sequence faster. while larger values will
allow for more time for the Input Sequence to be entered, making it easier to enter successfully.</td></tr>
<tr><td class=docleft width=1%><a href=CreateInputSequence.bmx class=small>Example</a></td><td class=docright><pre>SuperStrict

Import jmd.inputsequence



'Create a familiar "up,up,down,down,left,right,left,right,B,A,Enter" cheat code
Global livesCheat:TInputSequence = CreateInputSequence()
InSeqAddStroke(livesCheat,KEY_STROKE,KEY_UP)
InSeqAddStroke(livesCheat,KEY_STROKE,KEY_UP)
InSeqAddStroke(livesCheat,KEY_STROKE,KEY_DOWN)
InSeqAddStroke(livesCheat,KEY_STROKE,KEY_DOWN)
InSeqAddStroke(livesCheat,KEY_STROKE,KEY_LEFT)
InSeqAddStroke(livesCheat,KEY_STROKE,KEY_RIGHT)
InSeqAddStroke(livesCheat,KEY_STROKE,KEY_LEFT)
InSeqAddStroke(livesCheat,KEY_STROKE,KEY_RIGHT)
InSeqAddStroke(livesCheat,KEY_STROKE,KEY_B)
InSeqAddStroke(livesCheat,KEY_STROKE,KEY_A)
InSeqAddStroke(livesCheat,KEY_STROKE,KEY_ENTER)


'Create a  "God-Mode" cheat using InSeqAddKeyStrokesFromString()
'activated by typing "heaven" on the keyboard
Global godCheat:TInputSequence = CreateInputSequence()
InSeqAddKeyStrokesFromString(godCheat,"heaven")


'create an "add ammo" cheat that has some macro strokes!
'Activated by: KEY_UP+KEY_LEFT,KEY_SPACE,KEY_X (note that the first stroke is a macro of pressing 2 keys at once!)
Global ammoCheat:TInputSequence = CreateInputSequence(2000) 'Give a little extra time per stroke!
InSeqAddStroke(ammoCheat,KEY_STROKE,KEY_UP,1) 		'Notice that we are now specifying stroke numbers!
InSeqAddStroke(ammoCheat,KEY_STROKE,KEY_LEFT,1)		'KEY_UP and KEY_LEFT are now a "macro-stroke" for the first stroke!
InSeqAddStroke(ammoCheat,KEY_STROKE,KEY_SPACE,2)
inSeqAddStroke(ammoCheat,KEY_STROKE,KEY_X)			'Didn't specify the stroke on this one, which puts it in Auto mode...
													'This means that is will automatically be assigned the next stroke number (which would be 3 in this case)
													
'Create a "super-punch" special move
'activated by LMB,LMB,RMB,LMB,KEY_SPACE
'(LMB is Left Mouse Button, RMB is Right Mouse Button)
Global superPunch:TInputSequence = CreateInputSequence()
InSeqAddStroke(superPunch,MOUSE_STROKE,1)
inSeqAddStroke(superPunch,MOUSE_STROKE,1)
InSeqAddStroke(superPunch,MOUSE_STROKE,2)
InSeqAddStroke(superPunch,MOUSE_STROKE,1)
InSeqAddStroke(superPunch,KEY_STROKE,KEY_SPACE)




'We are starting with 3 lives
Local lives:Int = 3
'We are starting with 100 rounds of ammo
Local ammo:Int= 100

Local godModeString:String = "God Mode Active!!"

'Lets use a fun sound effect for when we perform the Livescheat code properly!
Local sndCredit:TSound=LoadSound("credit.wav")

Local kerplowTimestamp:Int





'Main loop
Graphics 640,480
While Not KeyDown(KEY_ESCAPE)
	Cls
	DrawText "Lives: " + lives, 10,10
	DrawText "Ammo: " + ammo, 500,10
	
	
	
	InSeqUpdateAll() 'must call this every iteration!!!
	
	'god mode cheat
	InSeqSuccessful(godCheat)
	If InSeqEntered(godCheat)>0 
		SetColor 255,0,0
		DrawText godModeString,GraphicsWidth()/2-TextWidth(godModeString)/2,10
		SetColor 255,255,255
	EndIf
	
	
	'ammo cheat
	If InSeqSuccessful(ammoCheat)
		If InSeqEntered(ammoCheat)>1
			Print "Oops! You can only do the ammo cheat once!"
		Else
			PlaySound sndCredit
			ammo=9999
		EndIf
	EndIf
	
	
	
	'lives cheat
	If InSeqSuccessful(livesCheat)
		PlaySound(sndCredit)
		lives:+ 30
	EndIf
	
	
	
	'Super punch sequence!
	If InSeqSuccessful(superPunch) Then kerplowTimestamp=MilliSecs()
	If InSeqEntered(superPunch)
		SetColor 255,0,0
		Local scale:Float=Sin((MilliSecs()/50)*10)
		SetScale Abs(scale)+1,Abs(scale)+1
		DrawText "KERPLOW!!!",GraphicsWidth()/2-TextWidth("KERPLOW!!")/2,GraphicsHeight()/2
		SetScale 1,1
		SetColor 255,255,255
		If MilliSecs() - kerPlowTimestamp > 3000 Then InSeqResetEntered(superPunch)
	EndIf
	
	
	ShowDebugInfo()
	Flip
Wend

End

Function ShowDebugInfo()
	DrawText "livesCheat: " + livesCheat.strokeCounter + " out of " + livesCheat.numStrokes + " strokes.",10,400
	DrawText "godCheat: " + godCheat.strokeCounter + " out of " + godCheat.NumStrokes + " strokes.",10,420
	DrawText "ammoCheat: " + ammoCheat.strokeCounter + " out of " + ammoCheat.numStrokes + " strokes.",10,440
	DrawText "superPunch: " + superPunch.StrokeCounter + " out of " + superPunch.numStrokes + " strokes.",10,460
End Function</pre></td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=FreeInputSequence>
<tr><td class=doctop colspan=2>Function FreeInputSequence(thisInputSequence:TInputSequence)</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>Release the TInputSequence instance.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>Free the TInputSequence input so that the garbage collector can clean up.
note: You must manually free the instance, or the CG will not clean up and it will create a small memory leak.
This is because the TInputSequence type stores a global list of instances, so merely setting your instance to null will not
trip the GC to do its job.</td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=InSeqAddKeyStrokesFromString>
<tr><td class=doctop colspan=2>Function InSeqAddKeyStrokesFromString(thisInputSequence:TInputSequence,thisString:String)</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>Batch add keystrokes from a string.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>This is a convenience function to easily add many <b>KEYSTROKE</b>s at once. This is useful for text-based cheat codes
such as having the user type "heaven" for god-mode, or "ammo-up" to add ammo, for example.</td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=InSeqAddStroke>
<tr><td class=doctop colspan=2>Function InSeqAddStroke(thisInputSequence:TInputSequence,strokeType:Int,strokeValue:Int,strokeNumber:Int=0)</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>Add to the Input Sequence.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>Add a "stroke" to the Input Sequence. At this time, each stroke can be a
keyboard key, or a joystick button.
the <b>strokeType</b> parameter expects either <b>KEY_STROKE</b> or <b>JOY_STROKE</b>. The <b>strokeValue</b> parameter
will either be a keyboard code (I.e. <b>KEY_SPACE</b>) or a joystick button number, depending on which value
was used for <b>strokeType</b>.</td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=InSeqClear>
<tr><td class=doctop colspan=2>Function InSeqClear(thisInputSequence:TInputSequence)</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>Clear all strokes from Input Sequence.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>Use this function to clear/remove all strokes from the Input Sequence.  This could be used, for example,
if the player changed control configuration and you need to rebuild the Input Sequence using the new strokes.</td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=InSeqEntered>
<tr><td class=doctop colspan=2>Function InSeqEntered:Int(thisInputSequence:TInputSequence)</td></tr>
<tr><td class=docleft width=1%>Returns</td><td class=docright>The number of times an Input Sequencet has been entered successfully.</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>Track Input Sequence successes.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>This is a convenience function for tracking how many times an Input Sequence has been entered. This is useful if you wish to limit
the number of times a cheat code can be performed by the user for example - such as only allowing an "add ammo" cheat to be used once per game.
example:
<pre>
if InSeqSuccessful(ammoCheat)
if InSeqEntered(ammoCheat)>1
print "Oops!  You can only use that cheat once!"
else
player.ammo:+ 1000 'add the ammo!
endif
endif
</pre>
<p>
see also: InSeqResetEntered()</td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=InSeqResetEntered>
<tr><td class=doctop colspan=2>Function InSeqResetEntered(thisInputSequence:TInputSequence)</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>Reset the Input Sequence tracking.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>Use this function to reset the Input Sequence tracking back to 0.</td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=InSeqSuccessful>
<tr><td class=doctop colspan=2>Function InSeqSuccessful:Int(thisInputSequence:TInputSequence)</td></tr>
<tr><td class=docleft width=1%>Returns</td><td class=docright><b>True</b> if anInput Sequence was successfully entered, false otherwise.</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>Check If an Input Sequence was successfully entered.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>Us this to check if an Input Sequence was entered successfully.</td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=InSeqUpdateAll>
<tr><td class=doctop colspan=2>Function InSeqUpdateAll()</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>Update all InputSequences.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>This function must be called every iteration of your loop. It is responsible for
updating the state of all of your TInputSequence instances!</td></tr>
</table>
<br>
<h2
 id=typesdet>Types
</h2>
<table class=doc width=100% cellspacing=3 id=TInputSequence>
<tr><td class=doctop colspan=2>Type TInputSequence</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>TInputSequence type.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>This is the type used and accessed by your program.</td></tr>
</table>
<table class=doc width=90% align=center><tr ><th class=doctop colspan=2 align=left><a name=TInputSequence_methods></a>Methods Summary</th></tr>
<tr><td class=docleft width=1%><a href=#AddKeyStrokesFromString>AddKeyStrokesFromString</a></td><td class=docright>
alternative for <a href=#InSeqAddKeyStrokesFromString>InSeqAddKeyStrokesFromString</a>()
</td></tr>
<tr><td class=docleft width=1%><a href=#AddStroke>AddStroke</a></td><td class=docright>
alternative for <a href=#InSeqAddStroke>InSeqAddStroke</a>()
</td></tr>
<tr><td class=docleft width=1%><a href=#Clear>Clear</a></td><td class=docright>
alternative For <a href=#InSeqClear>InSeqClear</a>()
</td></tr>
<tr><td class=docleft width=1%><a href=#Entered>Entered</a></td><td class=docright>
alternative For <a href=#InSeqEntered>InSeqEntered</a>()
</td></tr>
<tr><td class=docleft width=1%><a href=#ResetEntered>ResetEntered</a></td><td class=docright>
alternative For <a href=#InSeqResetEntered>InSeqResetEntered</a>()
</td></tr>
<tr><td class=docleft width=1%><a href=#Successful>Successful</a></td><td class=docright>
alternative For <a href=#InSeqSuccessful>InSeqSuccessful</a>()
</td></tr>
</table>
<table class=doc width=90% align=center><tr ><th class=doctop colspan=2 align=left><a name=TInputSequence_functions></a>Functions Summary</th></tr>
<tr><td class=docleft width=1%><a href=#Create>Create</a></td><td class=docright>
alternative for <a href=#CreateInputSequence>CreateInputSequence</a>()
</td></tr>
<tr><td class=docleft width=1%><a href=#UpdateAll>UpdateAll</a></td><td class=docright>
alternative for <a href=#InSeqUpdateAll>InSeqUpdateAll</a>()
</td></tr>
</table>
<table class=doc width=100% cellspacing=3 id=AddKeyStrokesFromString>
<tr><td class=doctop colspan=2>Method AddKeyStrokesFromString(thisString:String)</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>alternative for <a href=#InSeqAddKeyStrokesFromString>InSeqAddKeyStrokesFromString</a>()</td></tr>
</table>
<table class=doc width=100% cellspacing=3 id=AddStroke>
<tr><td class=doctop colspan=2>Method AddStroke(strokeType:Int,strokeValue:Int,strokeNumber:Int=0)</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>alternative for <a href=#InSeqAddStroke>InSeqAddStroke</a>()</td></tr>
</table>
<table class=doc width=100% cellspacing=3 id=Clear>
<tr><td class=doctop colspan=2>Method Clear()</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>alternative For <a href=#InSeqClear>InSeqClear</a>()</td></tr>
</table>
<table class=doc width=100% cellspacing=3 id=Entered>
<tr><td class=doctop colspan=2>Method Entered:Int()</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>alternative For <a href=#InSeqEntered>InSeqEntered</a>()</td></tr>
</table>
<table class=doc width=100% cellspacing=3 id=ResetEntered>
<tr><td class=doctop colspan=2>Method ResetEntered()</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>alternative For <a href=#InSeqResetEntered>InSeqResetEntered</a>()</td></tr>
</table>
<table class=doc width=100% cellspacing=3 id=Successful>
<tr><td class=doctop colspan=2>Method Successful:Int()</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>alternative For <a href=#InSeqSuccessful>InSeqSuccessful</a>()</td></tr>
</table>
<table class=doc width=100% cellspacing=3 id=Create>
<tr><td class=doctop colspan=2>Function Create:TInputSequence(thisTimeOut:Int=500)</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>alternative for <a href=#CreateInputSequence>CreateInputSequence</a>()</td></tr>
</table>
<table class=doc width=100% cellspacing=3 id=UpdateAll>
<tr><td class=doctop colspan=2>Function UpdateAll()</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>alternative for <a href=#InSeqUpdateAll>InSeqUpdateAll</a>()</td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=Tstroke>
<tr><td class=doctop colspan=2>Type Tstroke</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>TStroke type.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>This type is used internally, and is not normally used from outside of this module.</td></tr>
</table>
<br>
<h2 id=modinfo>Module Information</h2>
<table width=100%>
<tr><th width=1%>Version</th><td>1.0</td></tr>
<tr><th width=1%>Author</th><td>Jonathan Decker</td></tr>
<tr><th width=1%>License</th><td>GNU GPL v3</td></tr>
<tr><th width=1%>SVN</th><td>http://jmd-blitzmax-modules.googlecode.com/svn/trunk/jmd.mod/inputsequence.mod</td></tr>
<tr><th width=1%>History</th><td>1.0</td></tr>
<tr><th width=1%>History</th><td>Initial release.</td></tr>
</body></html>
